/****************************************************************************
 * Copyright (C) 2025 Chenyz. All rights reserved.
 *
 * @file    TinyOS_Lib.h
 *
 * @par     dependencies
 *          - stdint.h (Standard integer types)
 *          - string.h (String operations)
 *
 * @author  Chenyz
 *
 * @brief   TinyOS Core Library Header
 *          This file provides fundamental data structures and utilities
 *          used throughout the TinyOS real-time operating system, including:
 *          - Bitmap manipulation for resource management
 *          - Doubly-linked list implementation
 *          - Container utility macros and type definitions
 *          - Core data structure definitions
 *
 * @version V1.0
 * @date    2025-10-03
 *
 * @note    This library provides the foundational data structures and
 *          algorithms used by all TinyOS kernel components.
 ****************************************************************************/

#ifndef __TINYOS_LIB_H__
#define __TINYOS_LIB_H__

/******************************** Includes *********************************/
#include <stdint.h>
#include <string.h>

/******************************** Defines **********************************/

/**
 * @brief Container utility macro to get parent structure from member
 * 
 * This macro calculates the address of the parent structure given
 * a pointer to one of its members, using offsetof technique.
 * 
 * @param Node Pointer to the member node
 * @param Parent Type of the parent structure
 * @param Name Name of the member within the parent structure
 */
#define TINYOS_NODE_PARENT(Node, Parent, Name)  \
    (Parent*)((uint32_t)Node - (uint32_t)&((Parent *)0)->Name)

/***************************** Type Definitions ****************************/

/* Bitmap structure for efficient bit-level operations */
typedef struct {
    uint32_t BitmapData;
} TinyOS_BitmapType;

/* Doubly-linked list node structure */
typedef struct NodeType {
    struct NodeType*  PreNode;    /* Pointer to previous node */
    struct NodeType*  NextNode;   /* Pointer to next node */
} TinyOS_NodeType;

/* Doubly-linked list management structure */
typedef struct {
    TinyOS_NodeType   HeadNode;   /* Sentinel head node for list boundary */
    uint32_t          NodeCount;  /* Current number of nodes in the list */
} TinyOS_ListType;

/*************************** Function Declarations **************************/

/* Bitmap manipulation functions */
void TinyOS_BitmapInit(TinyOS_BitmapType* Bitmap);
void TinyOS_BitmapClear(TinyOS_BitmapType* Bitmap, uint32_t Position);
void TinyOS_BitmapSet(TinyOS_BitmapType* Bitmap, uint32_t Position);
uint32_t TinyOS_BitmapGetFirstBit(TinyOS_BitmapType* Bitmap);
uint32_t TinyOS_BitmapDataLength(TinyOS_BitmapType* Bitmap);
	
/* Linked list manipulation functions */
void TinyOS_ListDeleteNode(TinyOS_ListType* List, TinyOS_NodeType* DelteNode);
void TinyOS_ListInsertAfterNode(
	TinyOS_ListType* List, 
	TinyOS_NodeType* InsertNode, 
	TinyOS_NodeType* AfterNode
);
TinyOS_NodeType* TinyOS_ListHeadDelete(TinyOS_ListType* List);
void TinyOS_ListTailInsert(TinyOS_ListType* List, TinyOS_NodeType* Node);
void TinyOS_ListHeadInsert(TinyOS_ListType* List, TinyOS_NodeType* Node);
void TinyOS_ListRemoveAllNode(TinyOS_ListType* List);
TinyOS_NodeType* TinyOS_ListFindNextNode(TinyOS_ListType* List, TinyOS_NodeType* Node);
TinyOS_NodeType* TinyOS_ListFindPreNode(TinyOS_ListType* List, TinyOS_NodeType* Node);
TinyOS_NodeType* TinyOS_ListLastNode(TinyOS_ListType* List);
TinyOS_NodeType* TinyOS_ListFirstNode(TinyOS_ListType* List);
uint32_t TinyOS_ListNodeCount(TinyOS_ListType* List);
void TinyOS_ListInit(TinyOS_ListType* List);
void TinyOS_NodeInit(TinyOS_NodeType* Node);

#endif /* __TINYOS_LIB_H__ */

